.\" Process this file with
.\" groff -man -Tascii bdep-ci.1
.\"
.TH bdep-ci 1 "June 2024" "bdep 0.17.0"
.SH NAME
\fBbdep-ci\fR \- submit project test request to CI server
.SH "SYNOPSIS"
.PP
\fBbdep ci\fR [\fIoptions\fR] [\fIcfg-spec\fR] [\fIpkg-spec\fR]\fR
.PP
\fIcfg-spec\fR = (\fB@\fR\fIcfg-name\fR | \fB--config\fR|\fB-c\fR
\fIcfg-dir\fR)\.\.\. | \fB--all\fR|\fB-a\fR | \fB--forward\fR
.br
\fIpkg-spec\fR = (\fB--directory\fR|\fB-d\fR \fIpkg-dir\fR)\.\.\. |
\fIprj-spec\fR
.br
\fIprj-spec\fR = \fB--directory\fR|\fB-d\fR \fIprj-dir\fR\fR
.SH "DESCRIPTION"
.PP
The \fBci\fR command submits the project packages test request to a CI
server\.
.PP
If no project or package directory is specified, then the current working
directory is assumed\. If no configuration is specified, then the default
configurations are used\. If the specified directory is a project directory,
then all the packages initialized in the configurations are submitted, unless
the \fB--forward\fR option is specified (see below)\. See
\fBbdep-projects-configs(1)\fP for details on specifying projects and
configurations\.
.PP
A CI request consists of the specified packages and their versions as well as
the project's remote version control repository URL corresponding to the
current (local) state of the project\. The CI server should be able to fetch
these package versions from this repository as well as any dependencies from
this repository or its prerequisite/complement repositories, according to each
package's \fBrepositories\.manifest\fR\.
.PP
If the CI server is not explicitly specified with the \fB--server\fR option,
the request is submitted to \fBci\.cppget\.org\fR by default\.
.PP
Unless the remote repository URL is specified with the \fB--repository\fR
option, it will be automatically derived from the version control's "remote"
URL\. In case of \fBgit(1)\fR, it will be based on the
\fBremote\.origin\.url\fR configuration value unless overridden with
\fBremote\.origin\.build2Url\fR\. The repository URL is then adjusted to
corresponding to the current (local) state of the project\. In case of
\fBgit(1)\fR, the current branch and commit id are added as the repository URL
fragment (see \fBbpkg-repository-types(1)\fP for details)\.
.PP
Some package manifest values can be overridden as part of the CI request
submission using the \fB--override\fR and \fB--overrides-file\fR options as
well as their \fB--builds\fR, \fB--build-config\fR, \fB--target-config\fR,
\fB--package-config\fR, and \fB--build-email\fR shortcuts\. This is primarily
useful for specifying alternative build configurations and/or build
notification emails\. For example:
.PP
.nf
$ bdep ci --builds gcc
$ bdep ci --builds network/gcc
$ bdep ci --target-config 'linux*-gcc*'
$ bdep ci --package-config network
$ bdep ci --build-config 'network/linux*-gcc*'

$ bdep ci --override \\
  'default-build-config: config\.foo\.cache=true config\.foo\.buffer=16'

$ bdep ci --override 'mytest-build-config: config\.foo\.cache=true' \\
  --package-config mytest

$ bdep ci --override 'build-auxiliary: *-postgresql_16'
.fi
.PP
Manifest overrides other than [\fB*-\fR]\fBbuild-auxiliary\fR[\fB-*\fR]\fR
override the entire value group that they belong to\. The
[\fB*-\fR]\fBbuild-auxiliary\fR[\fB-*\fR]\fR values only override the matching
values, which are expected to already be present in the package manifest\.
Currently, the following value groups/values can be overridden\. The
\fBbuild-*email\fR group is overridden by default as if by specifying an empty
build email\.
.PP
.nf
build-email build-{warning,error}-email
builds build-{include,exclude}
build-bot
*-builds *-build-{include,exclude}
*-build-bot
*-build-config
*-build-email *-build-{warning,error}-email

[*-]build-auxiliary[-*]
.fi
.PP
For the package configuration-specific build constraint, email, auxiliary, and
custom bot public key overrides, the corresponding configuration must exist in
the package manifest\. In contrast, the package configuration override
(\fB*-build-config\fR) adds a new configuration if it doesn't exist and
updates the arguments of the existing configuration otherwise\. In the former
case, all the potential build constraint, email, auxiliary, and custom bot
public key overrides for such a newly added configuration must follow the
corresponding \fB*-build-config\fR override\.
.PP
Note that the build constraints group values (both common and build package
configuration-specific) are overridden hierarchically so that the
[\fB*-\fR]\fBbuild-\fR{\fBinclude\fR,\fBexclude\fR}\fR overrides don't affect
the respective [\fB*-\fR]\fBbuilds\fR\fR values\.
.PP
Note also that the common and build package configuration-specific build
constraints group value overrides are mutually exclusive\. If the common build
constraints are overridden, then all the configuration-specific constraints
are removed\. Otherwise, if any configuration-specific constraints are
overridden, then for the remaining configurations the build constraints are
reset to \fBbuilds:\ none\fR\.
.PP
Similar to the build constraints groups, the common and build package
configuration-specific custom bot public key value overrides are mutually
exclusive\. If the common build custom bot public keys are overridden, then
all the configuration-specific custom bot public keys are removed\. Otherwise,
if any configuration-specific custom bot public keys are overridden, then for
the remaining configurations the custom bot public keys are left unchanged\.
.PP
Similar to the above, the common and build package configuration-specific
build emails group value overrides are mutually exclusive\. If the common
build emails are overridden, then all the configuration-specific emails are
removed\. Otherwise, if any configuration-specific emails are overridden, then
for the remaining configurations the build emails are reset to the empty
values and the build warning and error emails are removed (which effectively
disables email notifications for such configurations)\.
.PP
If supported by the CI service, a package can be tested interactively in a
specific build configuration using the \fB--interactive\fR|\fB-i\fR\fR
option\. In this mode the CI service provides the login information for the
execution environment and pauses the testing at the specified breakpoint\.
.PP
While the exact interpretation of the CI request depends on the specific
service, normally, the CI server will respond with a reference that can be
used to query the results\. See Package CI (#ci) for details on the CI request
handling\.
.PP
If the \fB--forward\fR option is specified then the forwarded configurations
are used instead of the default configurations\. In particular, this means
that in this mode the project doesn't need to be initialized and all that's
required is for package's source directories to be configured to forward to an
out of source build configuration (see \fBb(1)\fP for details on forwarded
configurations)\. This, for example, can be used to submit packages that don't
use the standard version\.
.SH "CI OPTIONS"
.IP "\fB--yes\fR|\fB-y\fR"
Don't prompt for confirmation before submitting\.
.IP "\fB--interactive\fR|\fB-i\fR \fIcf\fR[:\fIbp\fR]"
Test the package interactively in the specified build configuration, pausing
the execution at the specified breakpoint\. The build configuration is a
target configuration (\fItc\fR), optionally for a specific package
configuration (\fIpc\fR) and/or for a specific target (\fItg\fR):

\fIcf\fR = [\fIpc\fR\fB/\fR]\fItc\fR |
\fIpc\fR\fB/\fR\fItc\fR\fB/\fR\fItg\fR\fR

Refer to the \fB--build-config\fR option for details on the build
configuration component semantics\. Note that for interactive testing they
should identify a single build configuration\. Failed that, the test request
will be aborted\.

Valid breakpoint values are \fBnone\fR (don't stop), \fBerror\fR (stop after
first error), \fBwarning\fR (stop after first warning), as well as the CI
service-specific step ids in which case the execution stops before performing
the specified step (see \fBbbot\fR worker step ids (bbot#arch-worker))\. If no
breakpoint is specified, then \fBerror\fR is assumed\.
.IP "\fB--server\fR \fIurl\fR"
CI server to submit the request to\.
.IP "\fB--repository\fR \fIurl\fR"
Remote repository URL for the project\.
.IP "\fB--override\fR \fIname\fR:\fIvalue\fR"
Package manifest value override\. Repeat this option to override multiple
values\.
.IP "\fB--overrides-file\fR \fIfile\fR"
Read manifest value overrides from the specified manifest fragment file\.
Repeat this option to specify multiple override files\.
.IP "\fB--builds\fR [\fIpc\fR/]\fIclass-expr\fR"
Shortcut for the following option:

\fB--override\ \fR[\fIpc\fR\fB-\fR]\fBbuilds:\fR\fIclass-expr\fR\fR

Repeat this option to specify multiple build target configuration classes\.
.IP "\fB--build-config\fR \fIpc\fR/\fItc\fR[/\fItg\fR]"
Shortcut for the following options sequence:

[\fB--override\ \fR\fIpc\fR\fB-builds:all\fR\fR]
.br
\fB--override\ \fR\fIpc\fR\fB-build-include:\fR\fItc\fR[\fB/\fR\fItg\fR]\fR
.br
\fB--override\ \fR\fIpc\fR\fB-build-exclude:**\fR\fR

The first override is omitted from the above sequence if the
\fIpc\fR\fB-builds\fR\fR override is specified on the command line\.

Repeat this option to specify multiple build configurations\.
.IP "\fB--target-config\fR \fItc\fR[/\fItg\fR]"
Shortcut for the following options sequence:

[\fB--override\ builds:all\fR\fR]
.br
\fB--override\ build-include:\fR\fItc\fR[\fB/\fR\fItg\fR]\fR
.br
\fB--override\ build-exclude:**\fR\fR

The first override is omitted from the above sequence if the \fBbuilds\fR
override is specified on the command line\.

Repeat this option to specify multiple build target configurations\.
.IP "\fB--package-config\fR \fIpc\fR"
Shortcut for the following options sequence:

\fB--override\ \fR\fIpc\fR\fB-builds:\fR\.\.\.\fR
.br
\fB--override\ \fR\fIpc\fR\fB-build-include:\fR\.\.\.\fR
.br
\fB--override\ \fR\fIpc\fR\fB-build-exclude:\fR\.\.\.\fR

Where the override values are the build constraints for the specified build
package configuration from the package manifest\.

Repeat this option to specify multiple build package configurations\.
.IP "\fB--build-email\fR \fIemail\fR"
Shortcut for the following option:

\fB--override\ build-email:\fR\fIemail\fR\fR
.IP "\fB--simulate\fR \fIoutcome\fR"
Simulate the specified outcome of the CI process without actually performing
any externally visible actions (such as testing the packages or publishing the
result)\. The commonly used outcome value is \fBsuccess\fR\. For other
recognized outcomes refer to the CI service documentation\.
.IP "\fB--forward\fR"
Use the forwarded configuration for each package instead of the default
configuration\.
.IP "\fB--all\fR|\fB-a\fR"
Use all build configurations\.
.IP "\fB--config\fR|\fB-c\fR \fIdir\fR"
Specify the build configuration as a directory\.
.IP "\fB--directory\fR|\fB-d\fR \fIdir\fR"
Assume project/package is in the specified directory rather than in the
current working directory\.
.IP "\fB--config-name\fR|\fB-n\fR \fIname\fR"
Specify the build configuration as a name\.
.IP "\fB--config-id\fR \fInum\fR"
Specify the build configuration as an id\.
.SH "COMMON OPTIONS"
.PP
The common options are summarized below with a more detailed description
available in \fBbdep-common-options(1)\fP\.
.IP "\fB-v\fR"
Print essential underlying commands being executed\.
.IP "\fB-V\fR"
Print all underlying commands being executed\.
.IP "\fB--quiet\fR|\fB-q\fR"
Run quietly, only printing error messages\.
.IP "\fB--verbose\fR \fIlevel\fR"
Set the diagnostics verbosity to \fIlevel\fR between 0 and 6\.
.IP "\fB--stdout-format\fR \fIformat\fR"
Representation format to use for printing to \fBstdout\fR\.
.IP "\fB--jobs\fR|\fB-j\fR \fInum\fR"
Number of jobs to perform in parallel\.
.IP "\fB--progress\fR"
Display progress indicators for long-lasting operations, such as network
transfers, building, etc\.
.IP "\fB--no-progress\fR"
Suppress progress indicators for long-lasting operations, such as network
transfers, building, etc\.
.IP "\fB--diag-color\fR"
Use color in diagnostics\.
.IP "\fB--no-diag-color\fR"
Don't use color in diagnostics\.
.IP "\fB--bpkg\fR \fIpath\fR"
The package manager program to be used for build configuration management\.
.IP "\fB--bpkg-option\fR \fIopt\fR"
Additional option to be passed to the package manager program\.
.IP "\fB--build\fR \fIpath\fR"
The build program to be used to build packages\.
.IP "\fB--build-option\fR \fIopt\fR"
Additional option to be passed to the build program\.
.IP "\fB--curl\fR \fIpath\fR"
The curl program to be used for network operations\.
.IP "\fB--curl-option\fR \fIopt\fR"
Additional option to be passed to the curl program\.
.IP "\fB--pager\fR \fIpath\fR"
The pager program to be used to show long text\.
.IP "\fB--pager-option\fR \fIopt\fR"
Additional option to be passed to the pager program\.
.IP "\fB--options-file\fR \fIfile\fR"
Read additional options from \fIfile\fR\.
.IP "\fB--default-options\fR \fIdir\fR"
The directory to load additional default options files from\.
.IP "\fB--no-default-options\fR"
Don't load default options files\.
.SH "DEFAULT OPTIONS FILES"
.PP
See \fBbdep-default-options-files(1)\fP for an overview of the default options
files\. For the \fBci\fR command the search start directory is the project
directory\. The following options files are searched for in each directory
and, if found, loaded in the order listed:
.PP
.nf
bdep\.options
bdep-ci\.options
.fi
.PP
The following \fBci\fR command options cannot be specified in the default
options files:
.PP
.nf
--directory|-d
.fi
.SH BUGS
Send bug reports to the users@build2.org mailing list.
.SH COPYRIGHT
Copyright (c) 2014-2024 the build2 authors.

Permission is granted to copy, distribute and/or modify this document under
the terms of the MIT License.
